home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 February: Tool Chest / Dev.CD Feb 97 TC.toast / Sample Code / Files / MoreFiles 1.4.4 / C Headers / MoreDesktopMgr.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-12-17  |  18.2 KB  |  499 lines  |  [TEXT/MPS ]
  1. /*
  2. **    Apple Macintosh Developer Technical Support
  3. **
  4. **    A collection of useful high-level Desktop Manager routines.
  5. **    If the Desktop Manager isn't available, use the Desktop file
  6. **    for 'read' operations.
  7. **
  8. **    We do more because we can...
  9. **
  10. **    by Jim Luther and Nitin Ganatra, Apple Developer Technical Support Emeriti
  11. **
  12. **    File:    MoreDesktopMgr.h
  13. **
  14. **    Copyright © 1992-1996 Apple Computer, Inc.
  15. **    All rights reserved.
  16. **
  17. **    You may incorporate this sample code into your applications without
  18. **    restriction, though the sample code has been provided "AS IS" and the
  19. **    responsibility for its operation is 100% yours.  However, what you are
  20. **    not permitted to do is to redistribute the source as "DSC Sample Code"
  21. **    after having made changes. If you're going to re-distribute the source,
  22. **    we require that you make it clear in the source that the code was
  23. **    descended from Apple Sample Code, but that you've made changes.
  24. */
  25.  
  26. #ifndef __MOREDESKTOPMGR__
  27. #define __MOREDESKTOPMGR__
  28.  
  29. #include <Types.h>
  30. #include <Files.h>
  31.  
  32. #include "PascalElim.h"
  33.  
  34. #ifdef __cplusplus
  35. extern "C" {
  36. #endif
  37.  
  38. /*****************************************************************************/
  39.  
  40. pascal    OSErr    DTOpen(ConstStr255Param volName,
  41.                        short vRefNum,
  42.                        short *dtRefNum,
  43.                        Boolean *newDTDatabase);
  44. /*    ¶ Open a volume's desktop database and return the desktop database refNum.
  45.     The DTOpen function opens a volume's desktop database. It returns
  46.     the reference number of the desktop database and indicates if the
  47.     desktop database was created as a result of this call (if it was created,
  48.     then it is empty).
  49.  
  50.     volName            input:    A pointer to the name of a mounted volume
  51.                             or nil.
  52.     vRefNum            input:    Volume specification.
  53.     dtRefNum        output:    The reference number of Desktop Manager's
  54.                             desktop database on the specified volume.
  55.     newDTDatabase    output:    true if the desktop database was created as a
  56.                             result of this call and thus empty.
  57.                             false if the desktop database was already created,
  58.                             or if it could not be determined if it was already
  59.                             created.
  60.     
  61.     Result Codes
  62.         noErr                0        No error
  63.         nsvErr                -35        Volume not found
  64.         ioErr                -36        I/O error
  65.         paramErr            -50        Volume doesn't support this function
  66.         extFSErr            -58        External file system error - no file
  67.                                     system claimed this call.
  68.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  69.                                     the Finder will fix this, but if your
  70.                                     application is not running with the
  71.                                     Finder, use PBDTReset or PBDTDelete
  72. */
  73.  
  74. /*****************************************************************************/
  75.  
  76. pascal    OSErr    DTXGetAPPL(ConstStr255Param volName,
  77.                            short vRefNum,
  78.                            OSType creator,
  79.                            Boolean searchCatalog,
  80.                            short *applVRefNum,
  81.                            long *applParID,
  82.                            Str255 applName);
  83. /*    ¶ Find an application on a volume that can open a file with a given creator.
  84.     The DTXGetAPPL function finds an application (file type 'APPL') with
  85.     the specified creator on the specified volume. It first tries to get
  86.     the application mapping from the desktop database. If that fails,
  87.     then it tries to find an application in the Desktop file. If that
  88.     fails and searchCatalog is true, then it tries to find an application
  89.     with the specified creator using the File Manager's CatSearch routine. 
  90.  
  91.     volName            input:    A pointer to the name of a mounted volume
  92.                             or nil.
  93.     vRefNum            input:    Volume specification.
  94.     creator            input:    The file's creator type.
  95.     searchCatalog    input:    If true, search the catalog for the application
  96.                             if it isn't found in the desktop database.
  97.     applVRefNum        output:    The volume reference number of the volume the
  98.                             application is on.
  99.     applParID        output:    The parent directory ID of the application.
  100.     applName        output:    The name of the application.
  101.     
  102.     Result Codes
  103.         noErr                0        No error
  104.         nsvErr                -35        Volume not found
  105.         ioErr                -36        I/O error
  106.         paramErr            -50        No default volume
  107.         rfNumErr            -51        Reference number invalid
  108.         extFSErr            -58        External file system error - no file
  109.                                     system claimed this call
  110.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  111.                                     the Finder will fix this, but if your
  112.                                     application is not running with the
  113.                                     Finder, use PBDTReset or PBDTDelete
  114.         afpItemNotFound        -5012    Information not found
  115.     
  116.     __________
  117.     
  118.     Also see:    FSpDTGetAPPL
  119. */
  120.  
  121. /*****************************************************************************/
  122.  
  123. pascal    OSErr    DTGetAPPL(ConstStr255Param volName,
  124.                           short vRefNum,
  125.                           OSType creator,
  126.                           short *applVRefNum,
  127.                           long *applParID,
  128.                           Str255 applName);
  129. /*    ¶ Find an application on a volume that can open a file with a given creator.
  130.     The DTGetAPPL function finds an application (file type 'APPL') with
  131.     the specified creator on the specified volume. It first tries to get
  132.     the application mapping from the desktop database. If that fails,
  133.     then it tries to find an application in the Desktop file. If that
  134.     fails, then it tries to find an application with the specified creator
  135.     using the File Manager's CatSearch routine. 
  136.  
  137.     volName        input:    A pointer to the name of a mounted volume
  138.                         or nil.
  139.     vRefNum        input:    Volume specification.
  140.     creator        input:    The file's creator type.
  141.     applVRefNum    output:    The volume reference number of the volume the
  142.                         application is on.
  143.     applParID    output:    The parent directory ID of the application.
  144.     applName    output:    The name of the application.
  145.     
  146.     Result Codes
  147.         noErr                0        No error
  148.         nsvErr                -35        Volume not found
  149.         ioErr                -36        I/O error
  150.         paramErr            -50        No default volume
  151.         rfNumErr            -51        Reference number invalid
  152.         extFSErr            -58        External file system error - no file
  153.                                     system claimed this call
  154.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  155.                                     the Finder will fix this, but if your
  156.                                     application is not running with the
  157.                                     Finder, use PBDTReset or PBDTDelete
  158.         afpItemNotFound        -5012    Information not found
  159.     
  160.     __________
  161.     
  162.     Also see:    FSpDTGetAPPL
  163. */
  164.  
  165. /*****************************************************************************/
  166.  
  167. pascal    OSErr    FSpDTGetAPPL(ConstStr255Param volName,
  168.                              short vRefNum,
  169.                              OSType creator,
  170.                              FSSpec *spec);
  171. /*    ¶ Find an application on a volume that can open a file with a given creator.
  172.     The FSpDTGetAPPL function finds an application (file type 'APPL') with
  173.     the specified creator on the specified volume. It first tries to get
  174.     the application mapping from the desktop database. If that fails,
  175.     then it tries to find an application in the Desktop file. If that
  176.     fails, then it tries to find an application with the specified creator
  177.     using the File Manager's CatSearch routine. 
  178.  
  179.     volName        input:    A pointer to the name of a mounted volume
  180.                         or nil.
  181.     vRefNum        input:    Volume specification.
  182.     creator        input:    The file's creator type.
  183.     spec        output:    FSSpec record containing the application name and
  184.                         location.
  185.     
  186.     Result Codes
  187.         noErr                0        No error
  188.         nsvErr                -35        Volume not found
  189.         ioErr                -36        I/O error
  190.         paramErr            -50        No default volume
  191.         rfNumErr            -51        Reference number invalid
  192.         extFSErr            -58        External file system error - no file
  193.                                     system claimed this call
  194.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  195.                                     the Finder will fix this, but if your
  196.                                     application is not running with the
  197.                                     Finder, use PBDTReset or PBDTDelete
  198.         afpItemNotFound        -5012    Information not found
  199.     
  200.     __________
  201.     
  202.     Also see:    DTGetAPPL
  203. */
  204.  
  205. /*****************************************************************************/
  206.  
  207. pascal    OSErr    DTGetIcon(ConstStr255Param volName,
  208.                           short vRefNum,
  209.                           short iconType,
  210.                           OSType fileCreator,
  211.                           OSType fileType,
  212.                           Handle *iconHandle);
  213. /*    ¶ Get an icon from the desktop database or Desktop file.
  214.     The DTGetIcon function retrieves the specified icon and returns it in
  215.     a newly created handle. The icon is retrieves from the Desktop Manager
  216.     or if the Desktop Manager is not available, from the Finder's Desktop
  217.     file. Your program is responsible for disposing of the handle when it is
  218.     done using the icon.
  219.  
  220.     volName        input:    A pointer to the name of a mounted volume
  221.                         or nil.
  222.     vRefNum        input:    Volume specification.
  223.     iconType    input:    The icon type as defined in Files.h. Valid values are:
  224.                             kLargeIcon
  225.                             kLarge4BitIcon
  226.                             kLarge8BitIcon
  227.                             kSmallIcon
  228.                             kSmall4BitIcon
  229.                             kSmall8BitIcon
  230.     fileCreator    input:    The icon's creator type.
  231.     fileType    input:    The icon's file type.
  232.     iconHandle    output:    A Handle containing the newly created icon.
  233.     
  234.     Result Codes
  235.         noErr                0        No error
  236.         nsvErr                -35        Volume not found
  237.         ioErr                -36        I/O error
  238.         paramErr            -50        Volume doesn't support this function
  239.         rfNumErr            -51        Reference number invalid
  240.         extFSErr            -58        External file system error - no file
  241.                                     system claimed this call
  242.         memFullErr            -108    iconHandle could not be allocated
  243.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  244.                                     the Finder will fix this, but if your
  245.                                     application is not running with the
  246.                                     Finder, use PBDTReset or PBDTDelete
  247.         afpItemNotFound        -5012    Information not found
  248. */
  249.  
  250. /*****************************************************************************/
  251.  
  252. pascal    OSErr    DTSetComment(short vRefNum,
  253.                              long dirID,
  254.                              ConstStr255Param name,
  255.                              ConstStr255Param comment);
  256. /*    ¶ Set a file or directory's Finder comment field.
  257.     The DTSetComment function sets a file or directory's Finder comment
  258.     field. The volume must support the Desktop Manager because you only
  259.     have read access to the Desktop file.
  260.  
  261.     vRefNum    input:    Volume specification.
  262.     dirID    input:    Directory ID.
  263.     name    input:    Pointer to object name, or nil when dirID
  264.                     specifies a directory that's the object.
  265.     comment    input:    The comment to add. Comments are limited to 200 characters;
  266.                     longer comments are truncated.
  267.     
  268.     Result Codes
  269.         noErr                0        No error
  270.         nsvErr                -35        Volume not found
  271.         ioErr                -36        I/O error
  272.         fnfErr                –43        File or directory doesn’t exist
  273.         paramErr            -50        Volume doesn't support this function
  274.         wPrErr                –44        Volume is locked through hardware
  275.         vLckdErr            –46        Volume is locked through software
  276.         rfNumErr            –51        Reference number invalid
  277.         extFSErr            -58        External file system error - no file
  278.                                     system claimed this call.
  279.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  280.                                     the Finder will fix this, but if your
  281.                                     application is not running with the
  282.                                     Finder, use PBDTReset or PBDTDelete
  283.     
  284.     __________
  285.     
  286.     Also see:    DTCopyComment, FSpDTCopyComment, FSpDTSetComment, DTGetComment,
  287.                 FSpDTGetComment
  288. */
  289.  
  290. /*****************************************************************************/
  291.  
  292. pascal    OSErr    FSpDTSetComment(const FSSpec *spec,
  293.                                 ConstStr255Param comment);
  294. /*    ¶ Set a file or directory's Finder comment field.
  295.     The FSpDTSetComment function sets a file or directory's Finder comment
  296.     field. The volume must support the Desktop Manager because you only
  297.     have read access to the Desktop file.
  298.  
  299.     spec    input:    An FSSpec record specifying the file or directory.
  300.     comment    input:    The comment to add. Comments are limited to 200 characters;
  301.                     longer comments are truncated.
  302.     
  303.     Result Codes
  304.         noErr                0        No error
  305.         nsvErr                -35        Volume not found
  306.         ioErr                -36        I/O error
  307.         fnfErr                –43        File or directory doesn’t exist
  308.         wPrErr                –44        Volume is locked through hardware
  309.         vLckdErr            –46        Volume is locked through software
  310.         rfNumErr            –51        Reference number invalid
  311.         paramErr            -50        Volume doesn't support this function
  312.         extFSErr            -58        External file system error - no file
  313.                                     system claimed this call.
  314.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  315.                                     the Finder will fix this, but if your
  316.                                     application is not running with the
  317.                                     Finder, use PBDTReset or PBDTDelete
  318.     
  319.     __________
  320.     
  321.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, DTGetComment,
  322.                 FSpDTGetComment
  323. */
  324.  
  325. /*****************************************************************************/
  326.  
  327. pascal    OSErr    DTGetComment(short vRefNum,
  328.                              long dirID,
  329.                              ConstStr255Param name,
  330.                              Str255 comment);
  331. /*    ¶ Get a file or directory's Finder comment field (if any).
  332.     The DTGetComment function gets a file or directory's Finder comment
  333.     field (if any) from the Desktop Manager or if the Desktop Manager is
  334.     not available, from the Finder's Desktop file.
  335.  
  336.     IMPORTANT NOTE: Inside Macintosh says that comments are up to
  337.     200 characters. While that may be correct for the HFS file system's
  338.     Desktop Manager, other file systems (such as Apple Photo Access) return
  339.     up to 255 characters. Make sure the comment buffer is a Str255 or you'll
  340.     regret it.
  341.     
  342.     vRefNum    input:    Volume specification.
  343.     dirID    input:    Directory ID.
  344.     name    input:    Pointer to object name, or nil when dirID
  345.                     specifies a directory that's the object.
  346.     comment    output:    A Str255 where the comment is to be returned.
  347.     
  348.     Result Codes
  349.         noErr                0        No error
  350.         nsvErr                -35        Volume not found
  351.         ioErr                -36        I/O error
  352.         paramErr            -50        Volume doesn't support this function
  353.         rfNumErr            –51        Reference number invalid
  354.         extFSErr            -58        External file system error - no file
  355.                                     system claimed this call.
  356.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  357.                                     the Finder will fix this, but if your
  358.                                     application is not running with the
  359.                                     Finder, use PBDTReset or PBDTDelete
  360.         afpItemNotFound        -5012    Information not found
  361.         
  362.     __________
  363.     
  364.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  365.                 FSpDTGetComment
  366. */
  367.  
  368. /*****************************************************************************/
  369.  
  370. pascal    OSErr    FSpDTGetComment(const FSSpec *spec,
  371.                                 Str255 comment);
  372. /*    ¶ Get a file or directory's Finder comment field (if any).
  373.     The FSpDTGetComment function gets a file or directory's Finder comment
  374.     field (if any) from the Desktop Manager or if the Desktop Manager is
  375.     not available, from the Finder's Desktop file.
  376.  
  377.     IMPORTANT NOTE: Inside Macintosh says that comments are up to
  378.     200 characters. While that may be correct for the HFS file system's
  379.     Desktop Manager, other file systems (such as Apple Photo Access) return
  380.     up to 255 characters. Make sure the comment buffer is a Str255 or you'll
  381.     regret it.
  382.     
  383.     spec    input:    An FSSpec record specifying the file or directory.
  384.     comment    output:    A Str255 where the comment is to be returned.
  385.  
  386.     Result Codes
  387.         noErr                0        No error
  388.         nsvErr                -35        Volume not found
  389.         ioErr                -36        I/O error
  390.         paramErr            -50        Volume doesn't support this function
  391.         rfNumErr            –51        Reference number invalid
  392.         extFSErr            -58        External file system error - no file
  393.                                     system claimed this call.
  394.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  395.                                     the Finder will fix this, but if your
  396.                                     application is not running with the
  397.                                     Finder, use PBDTReset or PBDTDelete
  398.         afpItemNotFound        -5012    Information not found
  399.         
  400.     __________
  401.     
  402.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  403.                 DTGetComment
  404. */
  405.  
  406. /*****************************************************************************/
  407.  
  408. pascal    OSErr    DTCopyComment(short srcVRefNum,
  409.                               long srcDirID,
  410.                               ConstStr255Param srcName,
  411.                               short dstVRefNum,
  412.                               long dstDirID,
  413.                               ConstStr255Param dstName);
  414. /*    ¶ Copy the file or folder comment from the source to the destination object.
  415.     The DTCopyComment function copies the file or folder comment from the
  416.     source to the destination object.  The destination volume must support
  417.     the Desktop Manager because you only have read access to the Desktop file.
  418.     
  419.     srcVRefNum    input:    Source volume specification.
  420.     srcDirID    input:    Source directory ID.
  421.     srcName        input:    Pointer to source object name, or nil when srcDirID
  422.                         specifies a directory that's the object.
  423.     dstVRefNum    input:    Destination volume specification.
  424.     dstDirID    input:    Destination directory ID.
  425.     dstName        input:    Pointer to destination object name, or nil when
  426.                         dstDirID specifies a directory that's the object.
  427.     
  428.     Result Codes
  429.         noErr                0        No error
  430.         nsvErr                -35        Volume not found
  431.         ioErr                -36        I/O error
  432.         fnfErr                –43        File or directory doesn’t exist
  433.         wPrErr                –44        Volume is locked through hardware
  434.         vLckdErr            –46        Volume is locked through software
  435.         paramErr            -50        Volume doesn't support this function
  436.         rfNumErr            –51        Reference number invalid
  437.         paramErr            -50        Volume doesn't support this function
  438.         extFSErr            -58        External file system error - no file
  439.                                     system claimed this call.
  440.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  441.                                     the Finder will fix this, but if your
  442.                                     application is not running with the
  443.                                     Finder, use PBDTReset or PBDTDelete
  444.         afpItemNotFound        -5012    Information not found
  445.         
  446.     __________
  447.     
  448.     Also see:    FSpDTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  449.                 FSpDTGetComment
  450. */
  451.  
  452. /*****************************************************************************/
  453.  
  454. pascal    OSErr    FSpDTCopyComment(const FSSpec *srcSpec,
  455.                                  const FSSpec *dstSpec);
  456. /*    ¶ Copy the desktop database comment from the source to the destination object.
  457.     The FSpDTCopyComment function copies the desktop database comment from
  458.     the source to the destination object.  Both the source and the
  459.     destination volumes must support the Desktop Manager.
  460.     
  461.     srcSpec        input:    An FSSpec record specifying the source object.
  462.     dstSpec        input:    An FSSpec record specifying the destination object.
  463.     
  464.     Result Codes
  465.         noErr                0        No error
  466.         nsvErr                -35        Volume not found
  467.         ioErr                -36        I/O error
  468.         fnfErr                –43        File or directory doesn’t exist
  469.         wPrErr                –44        Volume is locked through hardware
  470.         vLckdErr            –46        Volume is locked through software
  471.         paramErr            -50        Volume doesn't support this function
  472.         rfNumErr            –51        Reference number invalid
  473.         paramErr            -50        Volume doesn't support this function
  474.         extFSErr            -58        External file system error - no file
  475.                                     system claimed this call.
  476.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  477.                                     the Finder will fix this, but if your
  478.                                     application is not running with the
  479.                                     Finder, use PBDTReset or PBDTDelete
  480.         afpItemNotFound        -5012    Information not found
  481.         
  482.     __________
  483.     
  484.     Also see:    DTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  485.                 FSpDTGetComment
  486. */
  487.  
  488. /*****************************************************************************/
  489.  
  490. #ifdef __cplusplus
  491. }
  492. #endif
  493.  
  494. #ifndef __COMPILINGMOREFILES
  495. #undef pascal
  496. #endif
  497.  
  498. #endif    /* __MOREDESKTOPMGR__ */
  499.